// SAX locator interface for document events.
// No warranty; no copyright -- use this as you will.
// $Id: Locator.java,v 1.1 2000/11/07 05:21:24 garypeskin Exp $
using System;
namespace Comzept.Genesis.Tidy.Xml.Sax
{
	
	
	/// <summary> Interface for associating a SAX event with a document location.
	/// 
	/// <blockquote>
	/// <em>This module, both source code and documentation, is in the
	/// Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
	/// </blockquote>
	/// 
	/// <p>If a SAX parser provides location information to the SAX
	/// application, it does so by implementing this interface and then
	/// passing an instance to the application using the content
	/// handler's {@link org.Xml.Sax.ContentHandler#setDocumentLocator
	/// setDocumentLocator} method.  The application can use the
	/// object to obtain the location of any other content handler event
	/// in the XML source document.</p>
	/// 
	/// <p>Note that the results returned by the object will be valid only
	/// during the scope of each content handler method: the application
	/// will receive unpredictable results if it attempts to use the
	/// locator at any other time.</p>
	/// 
	/// <p>SAX parsers are not required to supply a locator, but they are
	/// very strongly encouraged to do so.  If the parser supplies a
	/// locator, it must do so before reporting any other document events.
	/// If no locator has been set by the time the application receives
	/// the {@link org.Xml.Sax.ContentHandler#startDocument startDocument}
	/// event, the application should assume that a locator is not 
	/// available.</p>
	/// 
	/// </summary>
	/// <since> SAX 1.0
	/// </since>
	/// <author>  David Megginson, 
	/// <a href="mailto:sax@megginson.com">sax@megginson.com</a>
	/// </author>
	/// <version>  2.0
	/// </version>
	/// <seealso cref="Comzept.Genesis.Tidy.Xml.Sax.ContentHandler.setDocumentLocator">
	/// </seealso>
	public interface Locator
	{
		/// <summary> Return the public identifier for the current document event.
		/// 
		/// <p>The return value is the public identifier of the document
		/// entity or of the external parsed entity in which the markup
		/// triggering the event appears.</p>
		/// 
		/// </summary>
		/// <returns> A string containing the public identifier, or
		/// null if none is available.
		/// </returns>
		/// <seealso cref="SystemId">
		/// </seealso>
		System.String PublicId
		{
			get;
			
		}
		/// <summary> Return the system identifier for the current document event.
		/// 
		/// <p>The return value is the system identifier of the document
		/// entity or of the external parsed entity in which the markup
		/// triggering the event appears.</p>
		/// 
		/// <p>If the system identifier is a URL, the parser must resolve it
		/// fully before passing it to the application.</p>
		/// 
		/// </summary>
		/// <returns> A string containing the system identifier, or null
		/// if none is available.
		/// </returns>
		/// <seealso cref="PublicId">
		/// </seealso>
		System.String SystemId
		{
			get;
			
		}
		/// <summary> Return the line number where the current document event ends.
		/// 
		/// <p><strong>Warning:</strong> The return value from the method
		/// is intended only as an approximation for the sake of error
		/// reporting; it is not intended to provide sufficient information
		/// to edit the character content of the original XML document.</p>
		/// 
		/// <p>The return value is an approximation of the line number
		/// in the document entity or external parsed entity where the
		/// markup triggering the event appears.</p>
		/// 
		/// <p>If possible, the SAX driver should provide the line position 
		/// of the first character after the text associated with the document 
		/// event.  The first line in the document is line 1.</p>
		/// 
		/// </summary>
		/// <returns> The line number, or -1 if none is available.
		/// </returns>
		/// <seealso cref="ColumnNumber">
		/// </seealso>
		int LineNumber
		{
			get;
			
		}
		/// <summary> Return the column number where the current document event ends.
		/// 
		/// <p><strong>Warning:</strong> The return value from the method
		/// is intended only as an approximation for the sake of error
		/// reporting; it is not intended to provide sufficient information
		/// to edit the character content of the original XML document.</p>
		/// 
		/// <p>The return value is an approximation of the column number
		/// in the document entity or external parsed entity where the
		/// markup triggering the event appears.</p>
		/// 
		/// <p>If possible, the SAX driver should provide the line position 
		/// of the first character after the text associated with the document 
		/// event.</p>
		/// 
		/// <p>If possible, the SAX driver should provide the line position 
		/// of the first character after the text associated with the document 
		/// event.  The first column in each line is column 1.</p>
		/// 
		/// </summary>
		/// <returns> The column number, or -1 if none is available.
		/// </returns>
		/// <seealso cref="LineNumber">
		/// </seealso>
		int ColumnNumber
		{
			get;
			
		}
	}
	
	// end of Locator.java
}